Skip to main content

VodaPay Access Token

/v2/authorizations/applyToken API​

The applyToken API is used by the Merchant to obtain the access token corresponding to an Auth Code. This API can be used in the following cases:

  • After the Merchant receives an authCode from Mini Program, the Merchant uses this API to request for the access token from e-wallet. In this scenario, the API generally needs to be used with the Authorization API.
  • When the original token expires, the merchant requests a new access token by using the refresh token. In this scenario, this interface can be used independently.

VodaPay Authorization Process​

VodaPayFlow empty

  1. The Mini Program calls the my.getAuthCode interface to obtain the authorization code from e-wallet. (Step 1)
  2. The e-wallet returns the authorization code to the Mini Program (Step 7)
  3. The Mini Program sends authorization code to the merchant server (Step 8)
  4. The merchant server calls the applyToken interface to apply for the access token from the e-wallet server and the e-wallet server returns the access token and customer ID to the merchant server. The access token should be kept in the merchant server only, which means that it should not be returned to the Mini Program. (Step 9 and Step 11).
info

Other steps are covered by the e-wallet.

Request Attributes​

As previously mentioned, the access token can be obtained with an Auth Code or Refresh Token.

note

When a Merchant requests an access token with an Auth Code they will receive a Refresh Token as part of the response and this can be used to request another token once the old one expires.

The Access Token can last up to 10 years before it expires.

Access Token Sample code​

POST
/v2/authorizations/applyToken

Request Headers
{
        "Content-Type": "application/json",
        "Client-Id": "2021072719************",
        "request-time": "2021-02-22T17:49:26.913+08:00",
        "Signature":"algorithm=RSA256, keyVersion=1, signature=testing_signatur"
}
Request Body With Auth Code
{
        "grantType": "AUTHORIZATION_CODE",
        "authCode": "0000000001NS2JbUdNT076MO00327491"
}
Request Body With Refresh Token
{
    "grantType": "REFRESH_TOKEN",
    "refreshToken": "2810111301lGZcM9CjlF91WH00039190"
}

Request Attributes with Auth Code​

  • grantType <String(16) | Mandatory>: If grantType is AUTHORIZATION_CODE this means the Auth Code is to be used to retrieve the accessToken.
  • authCode <String(32) | Mandatory>: Used by the Merchant to get an access token. After the user returns to the Mini program, the Merchant will get Auth Code from VodaPay and use it to request for an access token.
  • extendInfo <String(4096) | Optional>: A field that allows for additional information to be passed in with the request. This value is not used on the VodaPay side.

Request Attributes with Refresh Token​

  • grantType <String(16) | Mandatory>: If grantType is REFRESH_TOKEN this means the refresh token is to be used to retrieve the accessToken.
  • refreshToken <String(32) | Mandatory>: The refresh token, which is used by the Merchant to get a new access token when the access token has expired. By using the refresh token, new access token can be obtained without further interaction with the user.
  • extendInfo <String(4096) | Optional>: A field that allows for additional information to be passed in with the request. This value is not used on the VodaPay side.

Response Attributes​

  • result <Result | Mandatory>: The request result, which contains information related to the request result, such as status and error codes.
    • resultCode <string | Mandatory>: A single word providing an overview of the operation.
    • resultStatus <string | Mandatory>: A character that depicts the status of the request.
    • resultMessage <string | Mandatory>: A brief description of the status of the request.
  • accessToken <String(128) | Optional>: An access token that can be used to access the user resource scope. When authorization application is successful [result.resultStatus == S], the auth client might use accessToken to acccess the corresponding user's resource scope.
  • accessTokenExpiryTime <String/Datetime | Optional>: Access token expiration time, which follows the ISO 8601 standard. After this time, authClient will not be able to use this token to deduct from user's account.This parameter must be returned when authorization application is successful [result.resultStatus == S], and the accessToken will be invalid after accessTokenExpiryTime.
  • refreshToken <String (128) | Optional>: The refresh token that is used by the auth client to exchange for a new access token when the access token expires. By using the refresh token, new access tokens can be obtained without further interaction with the user. This parameter must be returned when authorization application is successful [result.resultStatus == S], and the merchant can use the refreshToken to request for a new accessToken.
  • refershTokenExpiryTime <String/Datetime | Optional>: Refresh token expiration time, after which the auth client cannot use this token to retrieve a new access token. The value follows the ISO 8601 standard. This parameter must be returned when authorization application is successful [result.resultStatus == S], and the merchant will not be able to use the refreshToken to retrieve a new accessToken after refreshTokenExpiryTime.
  • customerId <String(64) | Optional>: Resource owner id, maybe user id, app id of merchant's application, merchant id.
  • extendInfo <String (4096) | Optional>: The extend information,wallet and merchant can put extend info here.

Result process logic​

For different request results, different actions are to be performed. See the following list for details:

  • If the value of result.resultStatus is S, the authorization token application request is successful. The merchant can use the access token to access the corresponding user resource scope.
  • If the value of result.resultStatus is F or U, AuthClient may guide user to try again.

Result Statuses​

  • S SUCCESS: Success.
  • U UNKNOWN_EXCEPTION: An API calling is failed, which is caused by unknown reasons.
  • U REQUEST_TRAFFIC_EXCEED_LIMIT: The request traffic exceeds the limit.
  • F PROCESS_FAIL: A general business failure occurred. Don't retry.
  • F PARAM_ILLEGAL: Illegal parameters exist. For example, a non-numeric input, or an invalid date.
  • F ACCESS_DENIED: The access is denied.
  • F INVALID_API: The called API is invalid or not active.
  • F AUTH_CLIENT_UNSUPPORTED_GRANT_TYPE: The auth client do not support this grant type.
  • F INVALID_AUTH_CLIENT: The auth client id is invalid.
  • F INVALID_AUTH_CLIENT_STATUS: Invalid auth client status.
  • F INVALID_REFRESH_TOKEN: The refresh token is invalid.
  • F EXPIRED_REFRESH_TOKEN: The refresh token is expired.
  • F USED_REFRESH_TOKEN: The refresh token has been used.
  • F INVALID_CODE: The authorization code is invalid.
  • F USED_CODE: The authorization code has been used.
  • F EXPIRED_CODE: The authorization code is expired.
  • F REFERENCE_CLIENT_ID_NOT_MATCH: The reference client id does not match.
  • F EXPIRED_AGENT_TOKEN: The access token of mini program is expired.
  • F INVALID_AGENT_TOKEN: The access token of mini program is invalid.